******************************************************************
* Document type: Library reference
* Readme file name: manbpl.doc
* Library prefix: BPL
* Library name: Branching Playback
* Version: 1.00
* Creator: T.K.
* Created: 3/31/95
* Comments: None
******************************************************************

1. Warnings

1) Library Versions

   Use Ver.1.21 or later of the Stream System and File System
   libraries.

2) Prohibited SCU-DMA Use
   (A-Bus access prohibited during SCU-DMA transfer)

   The Branching Playback Library is not compatible with SCU-DMA
   transfers.  When using the Branching Playback Library, DMA
   transfer by the SCU is prohibited.  Use a Stream System
   transfer mode or function that does not use the SCU-DMA.

2. Manual

The Branching Playback Library manual is amended below.
The draft of the manual was output here as a text file, so
formatted items such as arrows may not display correctly.  Please
refer to the printed manual when it is released.

************ Draft Branching Playback Library Manual ************

1. Overview

The Branching Playback Library can be used to read streams based
on predetermined scenarios without interruption.  This allows
smooth branching between streams during reads.

However, note that the Branching Playback Library only manages
streams necessary for branching.  To playback an video or audio
from a stream, use a decoder library like MPEG, Cinepak,
TrueMotion, etc.

1.1 Library Configuration

The CD-related library configuration is shown in figure 1.1.

    +--------------------------------------------------------+
    |                    Application                         |
    +--------------------------------------------------------+
    +-------+ +-------------+ +---------------+ +-+  +-------+
    |       | |Cinepak      | | Branching     | | |  |       |
    |       | |Library (CPK)| | Playback      | | |  |       |
    |MPEG   | |             | | Library  (BPL)| | |  |       |
    |Library| +-------------+ +-------------+ | | |  | File  |
    |(MPG)  | +---------------------------------+ |  | System|
    |       | |                                   |  | (GFS) |
    |       | |       Stream System(STM)          |  |       |
    +-------+ +-----------------------------------+  +---+   |
    +--------------------------------------------------+ |   |
    |         CD communication interface (CDC)         | |   |
    +---------------------------+----------------------+ +-+-+
                                |                          |
Software                        |                          |
                                |                          |
--------------------------------+--------------------------+--
                                |                          |
                        +-------------+          +-----------+
Hardware                |  CD block   |          | SIMM, SCSI|
                        |             |          |   file    |
                        +-------------+          +-----------+

         Figure 1.1 CD related library configuration

The Stream System, File System, and CD Communication Interface
libraries are necessary to use the Branching Playback Library.

1.2 Branching Playback Library Functional Overview

1) Branch Destination Information (Scenario) Functional Overview

   Branch destination candidates for each stream are set as branch
   destination information (scenarios).

2) Function for Prereading Streams Required for Branching

   Opening and closing of streams managed in order to branch
   between streams smoothly.  By prereading open streams (branch
   destination candidates) to a CD buffer, branch destinations can
   be accessed as necessary without interruption.

3) Branch Destination Select Function

   Selects an actual branch destination from among branch
   destination candidates.

4) Branch Destination Stream Notify Function

   The application is notified of the next playback stream
   according to the selected branch destination.

             Initialization and branch
             destination information settings    +---------------+
      +------------------------------------------|               |
      V                                          |               |
+------------------+                             |  Application  |
|  Branching       |  Select branch destination  |               |
|  Playback        |  <------------------------  |               |
|  Library         |  ------------------------>  |               |
+------------------+        Stream handle        +---------------+
      | STM_Open, STM_Close                      Create, EntryNext
      |                                              |
      V                                              V
+------------------+               +-----------------------------+
|  Stream System   |               | Decoder (Cinepak, MPEG,etc.)|
+------------------+               +-----------------------------+

               Figure 1.2  Stream system overview

2. BPL Basics

2.1 Glossary of Terms and Abbreviations

Table 2.1 List of terms
+---------------+--------------------------------------------+
| Term          | Meaning                                    |
+---------------+--------------------------------------------+
| Branch stream | Corresponds to a file on a CD.  The branch |
|               | playback library, reads a stream based on  |
|               | the scenario information set for a branch  |
|               | stream.  By channel interleaving (normally |
|               | a subheader-based interleave) in a branch  |
|               | stream, different types of stream data     |
|               | (audio, video, etc.) can be accessed.      |
+---------------+--------------------------------------------+
| Branch stream | An identifier for identifying and          |
| identifier    | specifying branch streams. Branch          |
|               | destination information of read files and  |
|               | stream keys is set and accessed based on   |
|               | this identifier.                           |
+---------------+--------------------------------------------+
| Branch number | A number for specifying a branch           |
|               | destination. Corresponds to an event type  |
|               | input from a pad or other source.          |
+---------------+--------------------------------------------+

Table 2.2 List of abbreviations
+--------------+-------------------+--------------------------+
| Abbreviation | Meaning           |  Explanation             |
+--------------+-------------------+--------------------------+
| BPL          | branch play       | Branching playback       |
| bstm         | branch stream     | Branch stream            |
| bstmid       | branch stream ID  | Branch stream identifier |
| brno         | branch No.        | Branch number            |
| bstmmax      | branch stream max | Total # of registered    |
|              |                   | branch streams           |
| brmax        | branch max        | Total number of branches |
+--------------+-------------------+--------------------------+

Other terminology are taken from the CD Communication Interface,
File System, and Stream System.

2.2 Naming Restrictions

In the Branching Playback Library system, the following types of
names are used as function names, variable names, type names, and
macro names.

Function/variable names: BP~ and bp~
             Type names: Bp~
            Macro names: BP~

Libraries required for Branching Playback Library use the global
symbols shown below.

Table 2.3  Symbol names for each library
+----------------------------+---------------+
| Library name               | Symbol used   |
+----------------------------+---------------+
| Stream System              | ST~, st~, St~ |
+----------------------------+---------------+
| File System                | GF~, gf~, Gf~ |
+----------------------------+---------------+
| CD Communication Interface | CD~, cd~, Cd~ |
+----------------------------+---------------+

Application programs must not use these symbols.

3. Branching Playback Library Mechanism

3.1 Process Flow

The Branching Playback Library reads streams based on scenarios,
and notifies the application of the stream handles to be decoded
accordingly.

The main process flow is as shown in figure 3.1.

 +---------------------+
 | Initialization      |  <----Work area
 | (BPL_Init)          |       specification          +-------+
 +---------------------+                              |       |
           |                                          |       |
           |                                          |       |
           V                                          |   A   |
 +---------------------+                              |   P   |
 | Set scenario        |  <----Set branch stream      |   P   |
 |  BPL_SetStmInfo     |       and destination        |   L   |
 |  BPL_SetBranchInfo  |       information            |   I   |
 +---------------------+                              |   C   |
           |                                          |   A   |
+--------->|                                          |   T   |
|          V                  +--Select Branch        |   I   |
|+---------------------+      |  destination          |   O   |
|| Execute Branching   |    +-+  (BPL_SelectBranch)   |   N   |
|| Playback Server     |    |                         |       |
|| (BPL_ExecServer)    | <--+                         |       |
|+---------+-----------+ ------->Get branch stream    |       |
|          |                     BPL_GetCurStm        +-------+
+----------+                     BPL_GetNextStm

                   Figure 3.1 Process flow

3.2 Scenario

A scenario is time-based data which denotes how branching playback
is performed (i.e., in what sequence the streams will be played).

Branch streams are specified in file units.  Audio and video data
can be accessed by channel interleaving a file.


   Branch number              bstm6           bstm16
         0      bstm2         bstm7
                              bstm8
          1                   bstm9           bstm17        bstm19
  bstm1         bstm3         bstm10
          2                   bstm11
                              bstm12          bstm18
                bstm4         bstm13
         3                    bstm14

                bstm5         bstm15

                  Figure 3.2 Stream branching


a) With this scenario, the first branch stream read is bstm1.
   The Branching Playback Library starts reading bstm1.

b) The application fetches the current branch stream being read
   and directs sets it to the decoder.

c) After reading bstm1, the Branching Playback Library starts
   reading branch candidates (branch streams which may be
   accessed next) bstm2, bstm3, bstm4, and bstm5.  By reading the
   branch candidate streams in this way, the library takes
   advantage of the CD buffer.  This enables smooth branching to
   take place.

d) Applications receives an events from controller pad input or
   another source and selects a branch destination.  For example,
   if branch numbers from 0 to 3 are assigned to branches bstm2,
   bstm3, bstm4, and bstm5, and branch number 1 is specified, the
   reads to the unnecessary branches bstm2, bstm4, and bstm5 are
   stopped.

e) When access to bstm1 is completed, access to bstm3 starts.
   When the application requests the Branching Playback Server to
   execute branching as in c), the Branching Playback Library
   starts reading bstm9, bstm10, and bstm11.


3.3 Changes in Branching Playback Status

Branching playback status is shown in table 3.1, and changes in
branching playback status are shown in table 3.3.

Table 3.1 Branching playback status
+----------------------+-----------------------------------------+
| Status               | Explanation                             |
+----------------------+-----------------------------------------+
| End branching        | Branching playback completed.           |
| playback             | All stream groups and streams opened by |
|                      | the Branching Playback Library          |
|                      | (current stream and branch candidates)  |
|                      | are closed.                             |
+----------------------+-----------------------------------------+
| Wait for branch      | Branch candidates are preread, but a    |
| destination          | branch destination is not selected.     |
| selection            | All branch candidates streams are       |
|                      | preread. Only the current stream can be |
|                      | accessed.  The destination stream       |
|                      | cannot be accessed.                     |
+----------------------+-----------------------------------------+
| Branch destination   | A branch destination was selected from  |
| selected             | among the branch candidates. Only the   |
|                      | selected branch destination is preread. |
|                      | Both the current stream and branch      |
|                      | destination streams are accessed.       |
+----------------------+-----------------------------------------+
| No branch            | There is no branch candidate or branch  |
| destination          | destination for the current stream. The |
|                      | final stream is being played back.      |
+----------------------+-----------------------------------------+

The server function can access the branching playback status.


    +-----------------------------------+
    | Branching playback initialization |
    +-------------+---------------------+
                  |                   +--------------------------+
                  |  +----------------| Branching playback reset |
BPL_Init function |  | BPL_Reset      +--------------------------+
                  |  | function
                  |  |                      +--------------------+
                  |  |       +--------------| Branching playback |
                  V  V       | BPL_BR_None  | stopped            |
                             | is set by    +--------------------+
ON/OFF+-------------------+  | BPL_SetStart
+-----|  Branching        |  | function
|     |  playback         |<-+
+---> |  completed        |
      |                   |               Executable from all
      |(BPL_SVR_COMPLETED)|               conditions
      +------+-----+------+ <---------+
             |     ^                  |
BPL_SetStart |     |                  +-+
    function |     |                    |
             |     |  ON                +-+
             |     |                      |
             |     |                      +-+ ON
             V     |                        |
    OFF +------------------+              +------------------+ OFF
  +-----|Branch destination|              | No branch        |---+
  |     |select wait       +--------------+ destination      |   |
  +---> | (BPL_SVR_WAITSEL)|  No branch   | (BPL_SVR_NOBRN)  | <-+
        +------------------+  candidate   +------------------+
             |     ^                           ^
             |     |                         +-+
BPL_SelBranch|     | ON                      |
   function  |     |                       +-+
             V     |                       |
    OFF +------------------+             +-+
  +-----|Branch destination|             |
  |     |selected          |           +-+
  +---> |(BPL_SVR_SELECT)  |           |
        +------------------+ ----------+
                             The selected branch destination was
                             BPL_BR_None
                             (See the BPL_SetBranchInfo function)

*ON/OFF: If ON is specified for the Branching Playback Server
         function's (BPL_ExecServer) branch execution switch
         during branch destination select wait state or no branch
         destination state, branching playback ends.  If ON is
         specified for the branch destination selected state, the
         branch stream is switched.

       Figure 3.3 Branching playback status change diagram


3.4 Branch Execution (Branch Stream Switch Processing)

1) Branch Execution

   When branching is executed in the branch destination selected
   state (the branch execution switch of the Branching Playback
   Server is turned ON), the following branch stream switch
   processing is performed.

   a) Current stream A is closed.  (Read of A is stopped, and any
      data left in the CD buffer is cleared.)
   b) Branch destination stream B becomes the new current stream.
   c) The branch destination stream is unknown.

Table 3.2 Branch stream switching due to branching execution
+----------------+------------------+---------------------------+
| Branch stream  | Before branching | After branching           |
|                |                  | (after switching)         |
+----------------+------------------+---------------------------+
| Current stream |        A         | B                         |
| (Access with   |                  |  (A is closed)            |
| BPL_GetCurStm  |                  |                           |
| function)      |                  |                           |
+----------------+------------------+---------------------------+
| Branch         |        B         | Unknown until next        |
| destination    |                  | branch destination is     |
| stream         |                  | selected                  |
| (Access with   |                  | (Selected and set with    |
| BPL_GetNextStm |                  | BPL_SelectBranch function)|
| function)      |                  |                           |
+----------------+------------------+---------------------------+

Although branch destination selection always occurs before
branching (switching), the selection and switching operations are
basically done asynchronously.

2) Opening and Closing Streams

   Streams opened by the Branching Playback Library are current
   streams and branch candidate streams.  The open and close
   procedure is as follows.

   a) Playback start streams specified by the BPL_SetStart
      function are opened first as the current stream.
   b) When the current stream read starts, the branch candidate
      stream is opened.
   c) When a branch destination is selected, other branch
      candidates are closed, and only the branch destination is
      preread.
   d) When branching is executed, the current stream is closed.
      The branch destination stream is switched with the current
      stream, and steps b) to d) are repeated again.
   e) When branching playback ends, stream groups are closed.

3) Branch stream switching timing

   Branch stream switching timing is classified in table 3.3.

Table 3.3 Branch stream switching timing
+-------------------+--------------------------------------------+
| Timing            | Explanation                                |
+-------------------+--------------------------------------------+
| Normal switching  | When stream A decoding ends, a switch      |
|                   | occurs to branch destination stream B.     |
+-------------------+--------------------------------------------+
| Forced switching  | A forced switch to destination stream B    |
|                   | occurs during the decoding of stream A     |
+-------------------+--------------------------------------------+

Even if the branch destination is determined, branching must not
be executed until the decoder finishes processing the current
stream.  (This is done to prevent interruption of stream data
during decoding.)

For either normal or forced switching, perform the switch to the
decoder first. Turn the branch execution switch ON after that is
done.

4. Disc File Placement

The total number of streams which can be preread is equivalent to
the size of the CD buffer (maximum 200 sectors).  A delay will
occur in branching playback for streams which cannot be cached in
the buffer.

1) Non-Interleaved Branch Candidates

   When the branch candidates for stream A are B and C, and file
   placement on the disc is as shown in figure 4.1, only file B
   can be preread.

   There would be no problem if the seek and branch to B and C can
   be performed acceptably with the amount of data preread with
   stream A.  However, if it is necessary to preread both B and C
   in order to delay branch selection timing, it is not possible
   to execute branching without delay to C in this example.

Stream branching               File placement on disc
A --+-- B               +-----------+-------------+-------------+
    |                   |     A     |      B      |     C       |
    +-- C               +-----------+-------------+-------------+
                                     <----------->
                                  200 sectors or more

          Figure 4.1 Non-interleaved branch candidates
                     (Preread of C is impossible)

2) Complete Branch Candidate Interleave

B and C can be interleaved and placed after A as shown in figure
4.2 to branch to B and C without delay after playback of A.

Stream branching               File placement on disc
A --+-- B (b1+b2+b3...) +-----------+--+--+--+--+--+--+---------+
    |                   |     A     |b1|c1|b2|c2|b3|c3| ... ... |
    +-- C (c1+c2+c3...) +-----------+--+--+--+--+--+--+---------+
                                     <------------------------->
                                         B and C interleaved

Note: Branch candidate files are B and C.

Figure 4.2 Complete Branch Candidate Interleave (all of B and C)

3) Partial Branch Candidate Interleave

As shown in figure 4.3, B can be divided into B1 and B2, C can be
divided into C1 and C2, and just B1 and C1 can be interleaved on
disc.

In this case, it is acceptable for only a portion of B and C (B1,
C1) to be interleaved, and independent seeks to B2 and C2 is
possible.  However, the files must be divided.

Stream branching             File placement on disc
A ---+-----B1----B2    +----------+-------+----------+-----------+
     |                 |    A     | B1,C1 |    B2    |     C2    |
     +-----C1----C2    +----------+-------+----------+-----------+
                                   <----->
                            B1 and C1 interleaved

Note: Branch candidate files are B1, B2, C1, and C2.

Figure 4.3 Partial branch candidate interleave (part of B and C)

5. Basic Programming Example

5.1 Scenario Processing

Figure 5.1 shows an example of a branching playback scenario.

                          Branch #
                A button     0            BSTM2.MPG
     BSTM1.MPG
                B button     1            BSTM3.MPG

The A button is pressed during BSTM1.MPG playback.  After
BSTM1.MPG playback, BSTM2.MPG is played.

The B button is pressed during BSTM1.MPG playback.  After
BSTM1.MPG playback, BSTM3.MPG is played.

     Figure 5.1 Example of a branching playback scenario


An example of a program which sets this scenario is shown below.

#define BSTM_MAX    3   /* Total # of branches */
                        /* (BSTM1.MPG, BSTM2.MPG, BSTM3.MPG)  */
#define BRANCH_MAX  2   /* Total # of branches */
                        /* (Number of arrows in figure 5.1) */
#define KEY_MAX     2   /* Total number of stream key types */
#define A_BTN       0   /* A button branch number */
#define B_BTN       1   /* B button branch number */
#define BR_NUM      2   /* # of branches per stream */
#define BSTM1_ID    0   /* BSTM1.MPG branch stream identifier */
#define BSTM2_ID    1   /* BSTM2.MPG branch stream identifier */
#define BSTM3_ID    2   /* BSTM3.MPG branch stream identifier */

/* Branching Playback Library work area */
Sint32 work_bpl[BPL_WORK_SIZE(BSTM_MAX, BRANCH_MAX,
KEY_MAX)/sizeof(Sint32)];

void    setScenario(void)
{
  StmKey  key[KEY_MAX];   /* Stream key setting area */
  Sint32  brtbl[BR_NUM];  /* Branch destination setting area */
  Sint32  fid;            /* File identifier */

  /* Branching playback initialization */
  BPL_Init(BSTM_MAX, BRANCH_MAX, KEY_MAX, work_bpl);

  /* Branch stream information setting */
  STM_KEY_CN(key + 0) = STM_KEY_CIMSK(key + 0) = STM_KEY_None;
  STM_KEY_CN(key + 1) = STM_KEY_CIMSK(key + 1) = STM_KEY_None;
  STM_KEY_SMMSK(key + 0) = STM_KEY_SMVAL(key + 0) = STM_SM_VIDEO;
  STM_KEY_SMMSK(key + 1) = STM_KEY_SMVAL(key + 1) = STM_SM_AUDIO;
  fid = GFS_NameToId("BSTM1.MPG");
  BPL_SetStmInfo(BSTM1_ID, fid, KEY_MAX, key);
  fid = GFS_NameToId("BSTM2.MPG");
  BPL_SetStmInfo(BSTM2_ID, fid, KEY_MAX, key);
  fid = GFS_NameToId("BSTM3.MPG");
  BPL_SetStmInfo(BSTM3_ID, fid, KEY_MAX, key);

  /* Set branch destination information */
  brtbl[A_BTN] = BSTM2_ID;  /* Branch to STM2.MPG at
                               A button input */
  brtbl[B_BTN] = BSTM3_ID;  /* Branch to STM3.MPG at
                               B button input */
  BPL_SetBranchInfo(BSTM1_ID, BR_NUM, brtbl);
                            /* BSTM1.MPG branch destination
                               setting */
}

5.2 Branching Playback Processing

Following is an example of a branching playback program.  (See
section 5.1 for the scenario)

Sint32   work_gfs[GFS_WORK_SIZE(BSTM_MAX*KEY_MAX)/sizeof(Sint32)];
Sint32   work_stm[STM_WORK_SIZE(GRP_MAX,
         BSTM_MAX*KEY_MAX)/sizeof(Sint32)];
Sint32   brno;                    /* Branch number */
StmHn    stmtbl[KEY_MAX];         /* Stream handle table */
Sint32   bpl_stat;                /* Branching playback status */
Sint32   decode_stat;             /* Decoder operation status */
DecodeHn dc_hn = NULL;            /* Decoder handle */
Bool     chgsw = OFF;             /* Branch execution switch */
Bool     endflag = FALSE;
Sint32   ret;

/* Initialize each library */
GFS_Init(...);                    /* Initialize File System */
STM_Init(...);                    /* Initialize Stream System */
initDecoder();                    /* Initialize decoder */
setScenario();                    /* Set scenario (see 5.1) */

/* Branching playback */
BPL_SetStart(BSTM1_ID);           /* Set playback start stream */
BPL_GetCurStm(KEY_MAX, stmtbl);   /* Get first branch stream */
dc_hn = createDecodeHn(stmtbl);   /* Decoder handle creation */
while (endflag == FALSE) {
    bpl_stat = BPL_ExecServer(chgsw);
                           /* Execute Branching Playback Server */
    chgsw = OFF;
    STM_ExecServer();      /* Execute Stream Server */
    decode_stat = execDecoder(dc_hn);
                           /* Execute Decoder Server function */

    switch (bpl_stat) {
    case BPL_SVR_COMPLETED:
                          /* Branching playback complete status */
        endflag = TRUE;
        break;
    case BPL_SVR_WAITSEL:
                       /* Branch destination select wait status */

/* Get pad input (0: A button, 1: B button, negative: no input) */

        brno = getPadEvent();
        if (brno >= 0) {
            BPL_SelectBranch(brno);  /* Select branch dest. */
        }
        break;
    case BPL_SVR_SELECT:  /* Branch destination selected status */
    case BPL_SVR_NOBRN:   /*  No branch destination */
        if (decode_stat != COMPLETED) {
                          /* Decode completion check */
            break;
        }
        chgsw = ON;       /* Branching execution switch ON */
        ret = BPL_GetNextStm(KEY_MAX, stmtbl);
                          /* Get branch destination stream */
        if (ret >= 0) {   /* Branch destination exists */
            destoroyDecodeHn(dc_hn); /* Decoder handle cleared */
            dc_hn = createDecodeHn(stmtbl);
                          /* Decoder handle created */
        }
        break;
    }
}
destoroyDecodeHn(dc_hn);  /* Decoder handle cleared */

The opening and closing of streams is performed automatically with
the Branching Playback Library using the Stream System.  For
information on the decoder, see the manual for the applicable
decoder library.

6. Data Specifications

6.1 Basic Data
+----------------+----------------+-------------------+-----+
| Title          | Data           | Data Name         | No. |
|                |                |                   |     |
| Data Specs     | Basic data     |                   | 1.0 |
+----------------+----------------+-------------------+-----+

1) Basic Data Types
+------------+--------------------------------------------------+
| Type       | Explanation                                      |
+------------+--------------------------------------------------+
| Uint8      | Unsigned, 1 byte integer                         |
+------------+--------------------------------------------------+
| Sint8      | Signed, 1 byte integer                           |
+------------+--------------------------------------------------+
| Uint16     | Unsigned, 2 byte integer                         |
+------------+--------------------------------------------------+
| Sint16     | Signed, 2 byte integer                           |
+------------+--------------------------------------------------+
| Uint32     | Unsigned, 4 byte integer                         |
+------------+--------------------------------------------------+
| Sint32     | Signed, 4 byte integer                           |
+------------+--------------------------------------------------+
| Bool       | Boolean 4 byte integer (takes a logical constant |
|            | as the value)                                    |
+------------+--------------------------------------------------+

2) Logical Constants

Used as a Boolean value
+-----------------+--------+----------------------------------+
| Constant name   |  Value | Explanation                      |
+-----------------+--------+----------------------------------+
| FALSE           |   0    | Represents a false logical value.|
| TRUE            |   1    | Represents a true logical value. |
+-----------------+--------+----------------------------------+
| OFF             |   0    | Represents switch off (false).   |
| ON              |   1    | Represents switch on (true).     |
+-----------------+--------+----------------------------------+


6.2 Constants

+----------------+----------------+-------------------+-----+
| Title          | Data           | Data Name         | No. |
|                |                |                   |     |
| Data Specs     | Constant       |                   | 2.0 |
+----------------+----------------+-------------------+-----+

1) Error Code

The BPL_ERR_OK value is 0.  Other error codes are negative values.

+----------------------+-----------------------------------------+
| Constant name        | Explanation                             |
+----------------------+-----------------------------------------+
| BPL_ERR_OK           | Normal completion                       |
+----------------------+-----------------------------------------+
| BPL_ERR_KYOVRFLW     | Too many stream keys set                |
+----------------------+-----------------------------------------+
| BPL_ERR_BROVRFLW     | Too many branch destinations set        |
+----------------------+-----------------------------------------+
| BPL_ERR_BSTMID       | Invalid branch stream identifier        |
+----------------------+-----------------------------------------+
| BPL_ERR_BRNO         | Invalid branch number                   |
+----------------------+-----------------------------------------+
| BPL_ERR_BRSPC        | Branch destination is already specified |
+----------------------+-----------------------------------------+
| BPL_ERR_NOKEY        | Applicable stream key is not set        |
+----------------------+-----------------------------------------+
| BPL_ERR_OPNSTM       | Stream cannot be opened                 |
+----------------------+-----------------------------------------+

2) Other

+-----------------------+-------+--------------------------------+
| Constant name         | Value | Explanation                    |
+-----------------------+-------+--------------------------------+
| BPL_STMKEY_MAX        |   6   | Number of valid stream keys    |
|                       |       | possible in one branch stream. |
+-----------------------+-------+--------------------------------+

7. Function Specifications

Table 7.1 shows a list of Branching Playback Library functions.

Table 7.1 Function list 1
+------------------------------------+------------------+--------+
| Function                           | Function name    | Number |
+------------------------------------+------------------+--------+
| Scenario processing                                   |  1.0   |
| +----------------------------------+------------------+--------+
| | Initialize branching playback    | BPL_Init         |  1.1   |
| +----------------------------------+------------------+--------+
| | Reset branching playback         | BPL_Reset        |  1.2   |
| +----------------------------------+------------------+--------+
| | Set branch stream information    | BPL_SetStmInfo   |  1.3   |
| +----------------------------------+------------------+--------+
| | Get branch stream information    | BPL_GetStmInfo   |  1.4   |
| +----------------------------------+------------------+--------+
| |Set branch destination information| BPL_SetBranchInfo|  1.5   |
| +----------------------------------+------------------+--------+
| |Get branch destination information| BPL_GetBranchInfo|  1.6   |
| +----------------------------------+------------------+--------+
| Branching playback processing                         |  2.0   |
| +----------------------------------+------------------+--------+
| | Set playback start stream        | BPL_SetStart     |  2.1   |
| +----------------------------------+------------------+--------+
| | Execute Branching Playback Server| BPL_ExecServer   |  2.2   |
| +----------------------------------+------------------+--------+
| | Select branch destination        | BPL_SelectBranch |  2.3   |
| +----------------------------------+------------------+--------+
| | Get current stream               | BPL_GetCurStm    |  2.4   |
| +----------------------------------+------------------+--------+
| | Get branch destination stream    | BPL_GetNextStm   |  2.5   |
| +----------------------------------+------------------+--------+
| | Get stream group                 | BPL_GetStmGrp    |  2.6   |
| +----------------------------------+------------------+--------+


7.1 Scenario processing

+----------------+----------------+-------------------+-----+
| Title          | Function       | Function Name     | No. |
|                |                |                   |     |
| Function Specs | Initialize     | BPL_Init          | 1.1 |
|                | branching      |                   |     |
|                | playback       |                   |     |
+----------------+----------------+-------------------+-----+

Format:         Sint32 BPL_Init(Sint32 bstmmax, Sint32 brmax,
                Sint32 keymax, void *work)
Input: bstmmax: Total number of registered branch streams
         brmax: Total number of branches
        keymax: Total number of stream key types
          work: Work area
Output:         None
Function value: Error code
Function:       A work area is initialized to use the Branching
                Playback Library.  All previously set scenario
                information is cleared.
                Be sure to execute this function before using the
                Branching Playback Library.
Remarks:

a) The work area size is obtained by BPL_WORK_SIZE(bstmmax, brmax,
   keymax) bytes.  The work area must be placed in a 4 byte
   boundary.

   Example: Uint32 work[BPL_WORK_SIZE(bstmmax, brmax,
            keymax)/sizeof(Uint32)];

b) When setting different types of stream keys for different
   branch streams, the total number of types is the keymax value.

   Example: When setting key1 (3 key types) for bstm1 and key2 for
            bstm2 (4 key types), keymax is the sum of key1 and
            key2, which is 7.
            When setting the same key1 for bstm1 and bstm2, keymax
            is 3, the key1 value.

c) The BPL_Init function does not close the stream groups in use.
   To do a forced initialization while using the Branching
   Playback Library, execute the BPL_Reset function.

+----------------+----------------+-------------------+-----+
| Title          | Function       | Function Name     | No. |
|                |                |                   |     |
| Function Specs | Reset branching| BPL_Reset         | 1.2 |
|                | playback       |                   |     |
+----------------+----------------+-------------------+-----+

Format:         Sint32 BPL_Reset(void)
Input:          None
Output:         None
Function Value: Error code
Function:       Stops access to branch streams and resets
                branching playback.  (Closes stream groups used by
                the Branching Playback Library and initializes all
                data.)


+----------------+----------------+-------------------+-----+
| Title          | Function       | Function Name     | No. |
|                |                |                   |     |
| Function Specs | Set branch     | BPL_SetStmInfo    | 1.3 |
|                | stream         |                   |     |
|                | information    |                   |     |
+----------------+----------------+-------------------+-----+

Format:         Sint32 BPL_SetStmInfo(Sint32 bstmid, Sint32 fid,
                Sint32 nkey, StmKey *keytbl)
Input:  bstmid: Branch stream identifier (0 <= bstmid < bstmmax)
           fid: File identifier
          nkey: Stream key count (nkey <= BPL_STMKEY_MAX)
        keytbl: Stream key table
Output:         None
Function Value: Error code
Function:       Sets branch stream information (for each stream
                information actually read) for branch streams.
Remarks:

a) By setting multiple stream keys in one file, channel
   interleaved data can be read.
b) The maximum number of stream keys that can be set in one
   branch stream is BPL_STMKEY_MAX.  The total number of stream
   key types that can be used for all streams is specified with
   the BPL_Init function.

+----------------+----------------+-------------------+-----+
| Title          | Function       | Function Name     | No. |
|                |                |                   |     |
| Function Specs | Get branch     | BPL_GetStmInfo    | 1.4 |
|                | stream         |                   |     |
|                | information    |                   |     |
+----------------+----------------+-------------------+-----+

Format:         Sint32 BPL_GetStmInfo(Sint32 bstmid, Sint32 *fid,
                Sint32 *nkey, StmKey *keytbl)
Input:  bstmid: Branch stream identifier
Output:    fid: File identifier
          nkey: Stream key count (nkey <= BPL_STMKEY_MAX)
        keytbl: Stream key table
Function:       Gets branch stream information set in branch
                streams.  See the branch destination information
                setting function (BPL_SetBranchInfo) for the
                number of branch destinations.

+----------------+----------------+-------------------+-----+
| Title          | Function       | Function Name     | No. |
|                |                |                   |     |
| Function Specs | Set branch     | BPL_SetBranchInfo | 1.5 |
|                | destination    |                   |     |
|                | information    |                   |     |
+----------------+----------------+-------------------+-----+

Format:         Sint32 BPL_SetBranchInfo(Sint32 bstmid, Sint32
                nbranch, Sint32 *brtbl)
Input:  bstmid: Branch stream identifier
       nbranch: Number of branch destinations
         brtbl: Branch table
Output:         None
Function Value: Error code
Function:       Sets branch destination information (branch
                destination candidates) for branch streams.

Remarks:

a) Branch candidate branch stream identifiers are set in the
   branch table.  To set to no branch destinations, specify
   BPL_BR_None in the branch table.

     brtbl[0] = BSTMID_A;
     brtbl[1] = BPL_BR_None;
              /* No branch destination (Branching playback end) */
     brtbl[2] = BSTMID_B;
     nbranch = 3;

Branch destinations are set with the BPL_SelectBranch function and
branch number (position in the branch table).  In this example,
branch processing is performed according to the selected branch
destination.

+----------------------+-----------------------------------------+
| Selected branch      | Branch process                          |
| destination          | (server function branch                 |
|                      |   execution switch is ON)               |
+----------------------+-----------------------------------------+
| Branch no. 0         | Branch to branch stream identifier      |
|                      | BSTMID_A.                               |
+----------------------+-----------------------------------------+
| Branch no. 1         | Branching playback ends.                |
|                      | (Immediately after selection, goes into |
|                      |  no branch destination state            |
+----------------------+-----------------------------------------+
| Branch no. 2         | Branches to branch stream identifier    |
|                      | BSTMID_B.                               |
+----------------------+-----------------------------------------+
| Other                | (BPL_SelectBranch returns a BPL_ERR_BRNO|
|                      | error; selection is invalid)            |
+----------------------+-----------------------------------------+

b) The stream count must meet the following conditions:

   X + Y <= Z

     X: Number of stream keys set in bstmid.
     Y: Total number of branch destination stream keys.
     Z: Maximum number of streams which can be opened
        simultaneously (specified with the STM_Init function)

+----------------+----------------+-------------------+-----+
| Title          | Function       | Function Name     | No. |
|                |                |                   |     |
| Function Specs | Get branch     | BPL_GetBranchInfo | 1.6 |
|                | destination    |                   |     |
|                | information    |                   |     |
+----------------+----------------+-------------------+-----+

Format:          Sint32 BPL_GetBranchInfo(Sint32 bstmid, Sint32
                 *nbranch, Sint32 *brtbl, Sint32 nelem)
Input:   bstmid: Branch stream identifier
          nelem: Branch table element count
Output: nbranch: Branch destination count (0 if there are no
                 branch candidates)
          brtbl: Branch table (Maximum number of nelem branch
                 candidates are stored from top)
Function Value:  Error code
Function:        Gets branch destination information set in branch
                 streams.

7.2 Branching Playback Processing

+----------------+----------------+-------------------+-----+
| Title          | Function       | Function Name     | No. |
|                |                |                   |     |
| Function Specs | Set playback   | BPL_SetStart      | 2.1 |
|                | start stream   |                   |     |
+----------------+----------------+-------------------+-----+

Format:         Sint32 BPL_SetStart(Sint32 bstmid)
Input:  bstmid: Branch stream identifier
                (BPL_BR_None: Branching playback stops)
Output:         None
Function Value: Error code
Function:       Specifies the playback start stream (branch stream
                at top of scenario).  When BPL_BR_None is
                specified as the branch stream identifier,
                branching playback stops.

+----------------+----------------+-------------------+-----+
| Title          | Function       | Function Name     | No. |
|                |                |                   |     |
| Function Specs | Execute        | BPL_ExecServer    | 2.2 |
|                | Branching      |                   |     |
|                | Playback       |                   |     |
|                | Server         |                   |     |
+----------------+----------------+-------------------+-----+

Format:         Sint32 BPL_ExecServer(Bool chgsw)
Input:   chgsw: Branch execution switch
                (ON: Do branch processing, OFF: No processing)
Output:         None
Function Value: Branching playback status
Function:       Executes the Branching Playback Server.  When the
                branch execution switch is ON, performs branch
                processing (branch stream switching process).

1) Branching Playback Status

+-------------------+--------------------------------------------+
| Constant name     | Explanation                                |
+-------------------+--------------------------------------------+
| BPL_SVR_COMPLETED | Branching playback completed               |
+-------------------+--------------------------------------------+
| BPL_SVR_WAITSEL   | Branch destination select wait             |
+-------------------+--------------------------------------------+
| BPL_SVR_SELECT    | Branch destination selected                |
+-------------------+--------------------------------------------+
| BPL_SVR_NOBRN     | No branch destination                      |
+-------------------+--------------------------------------------+

See section 3.3, "Changes in Branching Playback Status" for
information on branching playback status.

+----------------+----------------+-------------------+-----+
| Title          | Function       | Function Name     | No. |
|                |                |                   |     |
| Function Specs | Select branch  | BPL_SelectBranch  | 2.3 |
|                | destination    |                   |     |
+----------------+----------------+-------------------+-----+

Format:         Sint32 BPL_SelectBranch(Sint32 brno)
Input:    brno: Branch number
Output:         None
Function Value: Error code
Function:       Selects branch destinations according to the
                specified branch numbers.

Remarks:

a) When the branch execution switch is set to ON during
   BPL_ExecServer execution, branch processing is performed.  (The
   current branch is switched with the selected destination
   stream.)

b) Branch destination selection must be executed even if there is
   only one branch candidate.

+----------------+----------------+-------------------+-----+
| Title          | Function       | Function Name     | No. |
|                |                |                   |     |
| Function Specs | Get current    | BPL_GetCurStm     | 2.4 |
|                | stream         |                   |     |
+----------------+----------------+-------------------+-----+

Format:         Sint32 BPL_GetCurStm(Sint32 nelem, StmHn *stmtbl)
Input:   nelem: Stream handle table element count
                (nelem <= BPL_STMKEY_MAX)
Output: stmtbl: Stream handle table
Function Value: Branch stream identifier
                (no applicable branch stream when negative)
Function:       Gets the stream which is currently targeted for
                access (branch stream identifier and stream
                handle).
Remarks:

a) Stream handles for each stream key are set in the stream handle
   table.

+----------------+----------------+-------------------+-----+
| Title          | Function       | Function Name     | No. |
|                |                |                   |     |
| Function Specs | Get branch     | BPL_GetNextStm    | 2.5 |
|                | destination    |                   |     |
|                | stream         |                   |     |
+----------------+----------------+-------------------+-----+

Format:         Sint32 BPL_GetNextStm(Sint32 nelem, StmHn *stmtbl)
Input:   nelem: Stream handle table element count
                (nelem <= BPL_STMKEY_MAX)
Output: stmtbl: Stream handle table
Function Value: Branch stream identifier (Negative when there is
                no applicable branch stream)
Function:       Gets the branch destination stream
                (branch stream identifier and stream handle).
Remarks:

a) Stream handles for each stream key are set in the stream handle
   table.

b) The function value is always negative until a branch
   destination is selected (i.e. BPL_SelectBranch is executed).

+----------------+----------------+-------------------+-----+
| Title          | Function       | Function Name     | No. |
|                |                |                   |     |
| Function Specs | Get stream     | BPL_GetStmGrp     | 2.6 |
|                | group          |                   |     |
+----------------+----------------+-------------------+-----+

Format:         StmGrpHn BPL_GetStmGrp(void)
Input:          None
Output:         None
Function Value: Stream group handle
Function:       Gets the stream group handle used by the Branching
                Playback Library.
Remarks:

a) The Branching Playback Library opens 1 stream group during
   operation.  The stream group handle is NULL when branching
   playback is completed.

***************************end of file***************************
